What problem does this solve?

OpenAB's Helm chart is currently strong on the minimal install path, but it is too thin for many real Kubernetes deployments.

It does not currently expose several common deployment controls that operators typically expect from a reusable open-source chart, including:

• imagePullSecrets
• probes (livenessProbe, readinessProbe, startupProbe)
• lifecycle
• initContainers
• extraContainers
• extra volumes / volume mounts
• serviceAccountName binding
• chart-managed ServiceAccount with IRSA support
• Role / ClusterRole RBAC
• PodDisruptionBudget
• other pod-level and cluster-level deployment settings that are common in production clusters

This leaves users with a few unattractive options:

1. rebuild a custom image for relatively minor deployment-specific needs
2. patch rendered manifests after helm template
3. fork the chart just to add standard Kubernetes fields

A concrete example: operators who need agents to access AWS resources (via IRSA) or the Kubernetes API currently have to fork the chart to add ServiceAccount annotations and RBAC rules.

Closes: #397

Discord Discussion URL: https://discordapp.com/channels/1491295327620169908/1493841502529523732

At a Glance

┌─────────────────────────────────────┐
│ Current OpenAB Helm Chart           │
│ minimal install path                │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│ Missing common chart hooks          │
│ - imagePullSecrets                  │
│ - probes / lifecycle                │
│ - initContainers / extraContainers  │
│ - extra volumes / mounts            │
│ - ServiceAccount + RBAC             │
│ - PodDisruptionBudget               │
│ - polymorphic env (valueFrom)       │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│ This PR                             │
│ pod extensibility + SA/RBAC/PDB     │
│ + env + template fixes              │
└─────────────────────────────────────┘

Prior Art & Industry Research

OpenClaw:

I reviewed the local OpenClaw repository and its Kubernetes deployment manifests. While OpenClaw does not currently ship a Helm chart in this repo, it does treat startup bootstrap as a first-class deployment concern. In particular, it uses an initContainer to prepare configuration and workspace state before the main container starts.

This suggests:

• initContainers are a reasonable place for startup preparation
• bootstrap logic should be treated as deployment design, not an ad hoc workaround
• a hardened main container can stay simpler when initialization is separated

Reference:

• scripts/k8s/manifests/deployment.yaml

Hermes Agent:

I reviewed Hermes Agent's Docker and deployment documentation. Hermes takes a clearer stance on tool installation: stable toolchains should primarily be handled through custom images or clearly defined mutable runtime environments, not by stretching the chart into a package manager.

This suggests:

• serious toolchains should prefer custom images
• runtime bootstrap can exist, but it should stay lightweight and bounded
• Helm should expose deployment extension points, not replace image design

References:

• Dockerfile
• website/docs/user-guide/docker.md
• website/docs/getting-started/nix-setup.md

Other references:

I reviewed Bitnami charts and Helm / Kubernetes best practices. Bitnami's more mature charts commonly expose imagePullSecrets, serviceAccount, probes, lifecycle, initContainers, extraContainers, extraVolumes, extraVolumeMounts, extraEnvVarsCM, extraEnvVarsSecret, extraDeploy, and pdb. This PR adopts the subset of that surface area that fits under Deployment.spec.template plus the essential cluster-level resources (ServiceAccount, Role, ClusterRole, PDB).

Relevant upstream guidance also supports this direction:

• Helm chart values and template best practices
• Kubernetes guidance for initContainers
• Kubernetes guidance for private registry pulls via imagePullSecrets
• Kubernetes RBAC best practices for namespaced vs cluster-scoped access

Proposed Solution

This PR implements full pod / deployment extensibility plus chart-managed ServiceAccount, RBAC, and PodDisruptionBudget. Discord feedback from @tonylee led to expanding beyond the original Phase 1 scope to cover AWS IRSA + K8s API access scenarios.

Implemented scope:

Pod / Deployment extensibility

• imagePullSecrets (global + per-agent, with explicit opt-out, supports both K8s native and shorthand formats)
• per-agent imagePullPolicy (global default + per-agent override)
• per-agent serviceAccountName binding (for referencing externally-created SAs)
• livenessProbe, readinessProbe, startupProbe, lifecycle
• initContainers, extraContainers
• extraVolumes, extraVolumeMounts
• podAnnotations, podLabels (global + per-agent, merged with reserved-key protection)
• polymorphic env rendering (string values + valueFrom maps via kindIs "map")
• TOML env value escaping via toJson (fixes pre-existing injection risk)

Chart-managed resources (Phase 2)

• ServiceAccount (opt-in via serviceAccount.create, with annotations for IRSA and automountServiceAccountToken control)
• namespaced Role + RoleBinding (opt-in via rbac.create)
• cluster-scoped ClusterRole + ClusterRoleBinding (opt-in via rbac.createClusterRole)
• PodDisruptionBudget (opt-in via podDisruptionBudget.enabled, supports both minAvailable and maxUnavailable)

Template consistency

• unified discord.enabled gate via openab.discordEnabled helper (consistent behavior across configmap, deployment, secret)

Explicitly out of scope:

• extra ConfigMap / Secret creation — already covered by existing extraVolumes/extraVolumeMounts/envFrom, operators create their own K8s resources and reference them
• generic extra objects such as extraDeploy — deferred

For the "install tools" question specifically, the implementation keeps two clear paths:

1. Custom image — the preferred path for stable, repeatable, production-grade toolchains
2. initContainers + shared volume — a lightweight bootstrap path for small binaries or startup initialization

Safety & correctness

Three design decisions are load-bearing for correctness.

Reserved pod-metadata keys cannot be hijacked. agentPodLabels and agentPodAnnotations use mergeOverwrite(dict, global, per-agent, reserved), where the reserved key set is merged last. This guarantees:

• checksum/config annotation is always the chart-computed hash — users cannot accidentally pin it or disable rollout-on-config-change
• app.kubernetes.io/{name,instance,component} labels on the pod template always match spec.selector.matchLabels, so Deployment → Pod selector matching can never be broken by a user-supplied podLabels entry

Without this protection, a user who set podLabels.app.kubernetes.io/name: custom would silently produce duplicate YAML keys and a Deployment whose ReplicaSet could no longer match its own Pods.

Per-agent imagePullSecrets: [] explicitly opts out of the global list. The helper uses hasKey instead of a truthy check, so three states are distinguishable per agent:

• key omitted → inherit .Values.imagePullSecrets
• imagePullSecrets: [] → opt out (no pull secrets, even if global is set)
• imagePullSecrets: [foo] → replace with per-agent list

All new resources are opt-in with safe defaults. serviceAccount.create, rbac.create, rbac.createClusterRole, and podDisruptionBudget.enabled all default to false. Existing deployments see no behavioral change on upgrade — only new resources are created when operators explicitly opt in.

Backward compatibility for ServiceAccount binding. The existing agents.<x>.serviceAccountName field still works for referencing externally-created SAs. When serviceAccount.create: true is set, the chart-created SA takes precedence over the external reference.

Why this approach?

I do not think OpenAB should model every Kubernetes field at once, and I do not think Helm should become the primary mechanism for packaging arbitrary tools.

At the same time, the current chart is thin enough that users are pushed toward forking it for fairly normal deployment requirements. That creates unnecessary friction for a public chart.

This approach takes the middle path:

• keep the default chart simple — all new controls are opt-in
• expose the extension points that operators commonly expect
• keep custom images as the primary answer for serious tool installation
• treat initContainers bootstrap as a lightweight complement, not the main packaging model
• make chart-managed RBAC available for teams who need agents to access cloud resources or the K8s API, without requiring a fork

Tradeoffs and limitations:

• the chart surface will grow
• pod-metadata merge rules must be unambiguous and predictable — addressed by the reserved-last mergeOverwrite pattern
• PodDisruptionBudget combined with the hardcoded replicas: 1 has a known edge case (minAvailable: 1 prevents node drains) — documented with a comment in values.yaml

Alternatives Considered

1. Pod extensibility only; defer SA/RBAC/PDB — initially chosen, then expanded

The first iteration of this PR scoped to Deployment.spec.template only, deferring SA/RBAC/PDB. After Discord feedback (specifically operators needing IRSA + K8s API access), the scope was expanded to include chart-managed resources since those are the exact gaps that otherwise force a fork.

2. Implement everything at once — chosen

Including SA/RBAC/PDB in the same PR keeps related extensibility changes together. All new resources follow the existing per-agent multi-resource loop pattern and share the same helpers (e.g. agentFullname, selectorLabels). All defaults are opt-in, so the risk profile is no higher than the Phase 1 changes.

3. Extra ConfigMap / Secret creation — rejected

The existing extraVolumes/extraVolumeMounts/envFrom fields already cover this use case. Users create their own ConfigMaps/Secrets (with their preferred lifecycle management) and reference them. Adding chart-managed extras would duplicate functionality without clear benefit.

Validation

• helm lint charts/openab passes
• Rendering coverage added for:
  • imagePullSecrets (global + per-agent, both K8s native and shorthand formats)
  • per-agent imagePullPolicy
  • initContainers, extraContainers
  • extraVolumes / extraVolumeMounts
  • probes (livenessProbe, readinessProbe, startupProbe), lifecycle
  • serviceAccountName + chart-managed ServiceAccount
  • ServiceAccount automountServiceAccountToken + IRSA annotations
  • Role + RoleBinding + ClusterRole + ClusterRoleBinding
  • PodDisruptionBudget (minAvailable, maxUnavailable, percentage values)
  • pod annotations and labels (global + per-agent merged)
  • polymorphic env rendering (string, valueFrom, mixed)
• Hardening coverage added for:
  • reserved selector labels (app.kubernetes.io/{name,component}) cannot be hijacked by user podLabels
  • checksum/config annotation cannot be overridden by user podAnnotations
  • per-agent imagePullSecrets: [] opts out of the global list
  • per-agent podLabels override global for the same non-reserved key
  • list-typed env values rejected with clear error message
  • map-typed env values filtered from config.toml (TOML cannot represent valueFrom)
  • PDB fails loudly when both minAvailable and maxUnavailable are set
  • PDB fails loudly when neither is set
• Backward compatibility:
  • existing serviceAccountName still resolves to external SA
  • serviceAccount.create: true overrides external reference when both are set
• Manual deploy-oriented verification on a real cluster

Validation command:

helm unittest charts/openab

Result: 61 passed, 0 failed (across 8 suites)

DC: https://discord.com/channels/1491295327620169908/1493841502529523732/1494148867380219956